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Second Edition (July 1974) 


This is a major revision of, and obsoletes, GC21-7566-0 and Technical Newsletter 
GN21-7657. This manual has been extensively revised and should be reviewed in 
its entirety. 


Information concerning IBM System/3 Model 15 has been added to the manual. The 
entire section entitled Chapter 5. Using Console Devices has been removed from 
this manual. The KEY (Model 6 only) and DSPLY operation codes, formerly described 
in Chapter 5, are described in your RPG || reference manual. For information 
concerning the RPG II Inquiry facility (Rollout/Rollin), also formerly described in 
Chapter 5, see Related Publications, listed in the Preface. 


Changes are periodically made to the information herein; before using this publication 
in connection with the operation of 1BM systems, refer to the /BM System/3 
Bibliography , GC20-8080, for the editions that are applicable and current. 


Use this publication only for the purposes stated in the Preface. 


Publications are not stocked at the address below. Requests for copies of IBM 
publications and for technical information about the system should be made to your 
(BM representative or to the IBM branch office serving your locality. 


This publication could contain technical inaccuracies or typographical errors. Use the 
Reader's Comment Form at the back of this publication to make comments about this 
publication. If the form has been removed, address your comments to IBM Corporation, 
Publications, Department 245, Rochester, Minnesota 55901. Comments become the 
property of IBM. 


© Copyright International Business Machines Corporation 1971, 1974 


This manual explains the RPG II specifications necessary 
to process disk files using the IBM System/3 Model 6, 
Model 10 Disk System, and Model 15. The following 
types of files are discussed: 


@ Sequential 

@ Indexed 

® Direct 

@ Record Address 


Included are examples of creating and maintaining each 
of these file types. For information on how this pub- 
lication should be read, see How to Use This Publication, 
following the table of contents. 


This manual is intended for programmers who have a 
basic knowledge of the RPG 11 language, including the 
ability to describe sequential and indexed files as 
input files. The reader must be familiar with the 
information presented in the /BM System/3 Disk Con- 
cepts and Planning Guide, GC21-7571. 


Note: For detailed information concerning multi- 
volume disk files — concepts; Operation Control Lan- 
guage considerations; RPG II processing — see the 
publications listed under Related Publications which 
are appropriate for your System/3 model. 
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Preface 


Related Publications 

These publications are recommended for additional 

reference: 

General System/3 

e@ /BM System/3 Disk Concepts and Planning Guide, 
GC21-7571 

RPG I! References 


© /BM System/3 Model 6 RPG I! Reference Manual, 
$C21-7517 


® /BM System/3 RPG I! Reference Manual, SC21-7504 


OCL References 


© /BM System/3 Models 8 and 10 System Control 
Programming Reference Manual, GC21-7512 


@ /BM System/3 Model 15 System Control Programming 
Reference Manual, GC21-5077 


®@ /BM System/3 Models 4 and 6 Operation Control 
Language and Disk Utility Programs Reference 


Manual, GC21-7516 


@ /BM System/3 Model 15 System Control! Programming 
Concepts and Reference Manual, GC21-5162 
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How To Use This Publication 


This publication is divided into four chapters: 
1. Sequential Files 

2. Indexed Files 

3. Direct Files 

4. Record Address Files 


Each of the chapters discusses the RPG 11 specifications needed to create and 
maintain a certain type of file. Since the discussions in each chapter apply to 
a particular file organization, you need read only the chapter for the file 
organization you will use. 


This manual is designed to show you the entries that must be made in order for 

the system to identify the file and determine what functions are to be done. Other 
entries will be needed, but they depend on the job you are doing. Refer to the ref- 
erence manual for your system if you need information on these additional entries. 


Note Concerning Examples 


Most of the examples in this manual use MFCU input files and use 96-column card 
images to represent input records. This does not imply that either the MFCU or 
96-column cards must be used for input; any of several input devices can be used, 
depending on which System/3 model and configuration you have. 


If you are a Model 6 user, you would probably not use a card file for input, al- 
though you may use an online data recorder for card input. Instead, you would 
create sequential disk transaction files in one of the following ways: 


@ Using the Keyboard Data Entry conversational utility program (see /BM 
System/3 Model 6 Conversational Utility Programs Reference Manual, SC21-7528) 


@ Using an interactive RPG 11, FORTRAN, or BASIC program to build the disk 
file from keyboard input 
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The disk transaction file would then be used to update a disk master file in the 
same way MFCU files are used in the examples in this manual. Thus, the MFCU 
tiles in the examples could be replaced by sequential disk files. For example: 


File Description Specification 














Record 


Key Fietd 
Length i! 


Starting 
Location 


Continuation Lines 


Extension Code E/L 


VO/U/C/D 
P/S/C/R/T/D. 
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F File Type Mode of Processing File Addition/Unordered 
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Depending on the System/3 model and the I/O devices available, MFCU input files shawn 

in most of the examples can be replaced by 80-column card files, console files, tape files, 
5445 disk files, or other types of input files. Models 10, 12, and 15 users can substitute 
DISK45 (5445 disk) or DISK40 (3340 disk) for the device entry DISK (5444 disk) in the 
examples, depending on the equipment they have. Model 6 users should replace the device 
entry PRINTER in the examples with the device entry TRACTR1, and replace Block Length 


and Record Length entries with the beginning and ending print positions. 
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DIRECT ACCESS STORAGE FOR MODELS 12 AND 15 


The IBM 3340 Direct Access Storage Facility attaches to System/3 Model 12, to System/3 
Model 15 (5704-RG1), and to System/3 Mode! 15 (5704-RG2). 


The IBM 3344 Direct Access Storage Facility also attaches to System/3 Model 15 (5704-RG2). 


Certain areas on the 3340 and 3344 disks are treated as 5444 disks. These areas, known as 
5444 simulation areas, are used for the program libraries and can be also used for certain 


data files. The remainder of the disk space, known as main data area, can only be used for 
data files. 


References in this manual to DISK, DISK40, and DISK45 are to be interpreted according 
to which disk storage device(s) is attached to the system. The following table should be 
used to determine the meaning of the reference: 


Model 15 Model 12 or 15 Model 15 
Device Type (5704-RG1) (5704-RG1) (5704-RG2) 
5444 Disk 5444 simulation 5444 simulation 
Storage area on 3340 area on 3340 or 
Drive 3344 


DISK40 Not Main data area Main data area 
applicable on 3340 on 3340 or 3344 


DISK45 5445 Disk Main data area Main data area 
Storage on 3340 on 3340 or 3344 





IBM System/3 5448 Disk Storage Drive 


The IBM System/3 5448 Disk Storage Drive or System/3 Models 8 and 10 uses the same 
program product support as the IBM 5445 Disk Storage. However, a separate system 
control program feature is required for the 5448. In general, references to 5445 in this 
manual also apply to 5448. For specific information about 5448 operating characteristics 
and programming support, see /BM System/3 5448 Disk Storage Drive Program Reference 
Manual, GC21-51688. 


vii 
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Chapter 1. Sequential Files 


A sequential disk file is a group of records arranged in a particular sequence and 
processed consecutively, one after another in the order they occur. 


This chapter explains how to use the RPG II language to create and maintain a 
sequential file. Sample jobs are used to illustrate these functions. 


To understand the sample jobs, a basic knowledge of RPG II is necessary. If you 
do not fully recall some of the coding used in the sample jobs, you should refer 
to the /BM System/3 RPG I! Reference Manual, SC21-7504 (for Model 10 Disk 
System or Model 15), or the /BM System/3 Model 6 RPG I! Reference Manual, 
$C21-7517, depending on the system you have. 


CREATING A SEQUENTIAL FILE 


To create a sequential file, you make certain entries on the File Description 
sneet. The fo'lowiny entries are required to describe various characteristics of 
the disk file: 


File Description Specifications 


Device 


P99] au 41 ay 43 44 45 46) 





The disk filename must be entered in columns 7 through 14. Column 15 must 
contain an ©) to indicate the file is an output file. 


All records in a tile must be the same length. Thus, column 19 must contain an 
F to specify that the record length is fixed. 


A number that is equal to or a multiple of the disk record length must be 

entered in columns 20 through 23. This entry determines the size of the input/ 
output area allocated by RPG II. For an explanation on block length calculation, 
see the /BM Systerm/3 Disk Concepts and Planning Guide, GC21-7571. if you 
want block length calculated for you by RPG 11, assign a block length equal to the 
record length. By blocking disk records you can increase the input/output effi- 
ciency of your program by reducing the number of accesses. You must be sure, 
however, that enough main storage is available for your input/output area. 


Columns 24 through 27 must contain the length of the disk record. Whenever a 
disk fie is being described, DISK (Model 6, 10, 15), DISK40 (Model 12 or 15), 
ow DISK45 (Modei 10, 12, or 15) is required in the Device columns. 


Sequential Files 1 


Example of Creating a Sequential File 


Suppose you want to create a customer file on disk. Customer numbers are to be 

assigned on a sequential basis; new customers are assigned the next higher number. 
The file will be used to produce monthly reports of each customer’s status. Thus, 
a sequential file will serve your needs. 


To create the sequential file, you must first determine the input record format and 
the output record format (Figure 1). The file is created by writing the customer 
data from the input records onto disk. Notice that space is provided on the output 
record so additional information can be added to the record later if necessary. 

Basic information about each customer in the file is also printed in the report shown 
in Figure 2. 


Figure 3 shows the RPG II coding necessary to create the sequential customer file 
and print the report. 
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Key 
ADDR CITST CODE Output code (CM) 

CUSTNO Customer number 

STATE State 

co County 

CITY City 

NAME Customer name 

ADDR Customer street address 

CITST City and state 

CRLIM Credit limit 

STATUS = Status 

TRANS Number of transactions this month 
CHARGE Current month charges 

PAY Current month payments 
CREDIT Current month credits 

BAL Balance 

YTDSLS Year-to-date sales amount 

YTDNO Year-to-date number of sales 
DELETE Output record code 
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IBM 3706 


Note: The input file need not be a card file. See 
How to Use This Manual, Note Concerning Examples 
at the beginning of this manual. 





Output Record 
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Reserved space for 
record expansion 


DELETE 
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Figure 1. Input Record and Output Record Formats 
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CUSTOMER NAME 


ADDRESS 
136728 JONES VARIETY 14 S MAIN BEDROCK, TEX 
301628 JIM'S 5 AND 10 1103 FRANKLIN ST GLENCOE, MINN 
795246 SCHMIDT HARDWARE 600 1ST ST NW HILL CITY, MD 
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Figure 2. Report of Customer Records 
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Figure 3 (Part 1 of 2). 
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Figure 3 (Part 2 of 2). Creating a Sequential Customer File 


MAINTAINING A SEQUENTIAL FILE 





Once a file has been created, it usually needs to be maintained. File maintenance 
means performing those functions that keep a file current for daily processing 
needs. Four common “ile maintenance functions apply to sequential files: 


1. Adding records. 


Updating records. 


Reorganizing a file. 


Tagging records for deletion. 





Adding Records 


After a file is created, you can add records to it. Records can be added to a 
sequential file in either of two ways: 


1. At the end of records in the file. 


2. Between records in the file (creating a new file). 


Adding Records at the End of Records in the File 


To add records at the end of the file, entries are required on the File Descrip- 
tion and Output-Format sheets: 


File Description Specifications 





File Additian/Unordered 
















Filename Device 


File Format 








Block Record 
Length 


1/0/U/C/D 
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International Business Machines Corporation 


RPG OUTPUT - FORMAT SPECIFIZATIONS 


fan ete Me oy 1 es t i 1 
Bes Punching Graphic ; t | 
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Instruction [ Punch. oe Bee pu 
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Some of the entries on the File Description sheet are the same ones needed to 
create a sequential file (see Creating a Sequential File in this chapter). 


Two new disk entries are also needed, one on the File Description sheet and one 
on the Output-Format sheet. These entries are circled. 


An A in column 66 on the File Description sheet tells the system that records 
will be added to the file described on this fine. 


The entry on the Output-Format sheet is an ADD in columns 16 through 18. 


This entry tells the system that the fields defined on the following lines con- 
stitute the record to be added to the file specified in columns 7 through 14. 
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Example of Adding Records to the End of the File 


As you get new customers, you will want to add them to the sequential cus- 
tomer file you created in the Example of Creating a Sequential File. Since 
customer numbers are assigned sequentially, each new customer record can be 
added following the records now in the file. 


The input records and output records will be in the same format as the records 
used to create the file. A report can be printed like the one shown in Figure 4 
to ensure that the new records have been added to the file. 


Figure 5 shows the RPG 11 coding necessary to add records to the customer file 
and print the report. 
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NEW CUSTOMER LISTING 








CUSTOMER CUSTOMER CREDIT 


NUMBER NAME ADDRESS CITY/STATE LIMIT 
136728 JONES VARIETY 14 S MAIN BEDROCK, TEX 1,000 
301628 JIM'S 5 AND 10 11023 FRANKLIN ST GLENCOE, MINN 250 
795246 SCHMIDT HARDWARE 600 1ST ST Nw HILL CITY, MD 2,000 


a ee 


Figure 4. Report of New Customers Added to the Customer File 
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Merging Records Between Records in the File 


Often records must be added between existing records in a sequential disk file. 
When records must be added in this manner, you must sort the new records and 
re-create the file. This new file contains the added records merged in correct 
order with the records from the original file. 


Example of Merging Records Between Records in the File 


Figure 6 shows the RPG II coding necessary to merge records in the file. This 
example is similar to the Example of Adding Records to the End of the File 
in that the input and output records are the same format and the same report 
is printed. 
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Tagging Records for Deletion 


When a record becomes inactive, you may no longer want to process it with 
the other records. Since the record is not physically removed from the file, 
you must identify the record so it can be bypassed. One way to do this is 

to put a code, called a delete code, in a particular location in the record. 

This code can be any character you want. Any program that should not proc- 
ess deleted records can check for this code. If the code is present, the program 
can bypass the record. The deleted records can be physically removed when 
the file is reorganized (see Reorganizing a File in this section). 


Example of Tagging Records for Deletion 


An example of tagging records for deletion is shown in this section under 
Updating Records, Example of Updating Records. 


Updating Records 


Many jobs require changes to certain data in a record. This function is called 
updating. To update disk files, the following entries are required on the File 
Description sheet: 


File Description Specifications 


File Type 


File Designation 


Filename Device 


File Format 


Block 
Length 


$9440 41 42 43 44 45 46f3 





Some of the entries are the same entries needed to create a sequential file and 
were discussed in this chapter under Creating a Sequential File. 


The two new entries are circled. Column 15 must contain a U to indicate that 
the file is an update file. Column 16 can contain either a P or an S depending 
on whether the file is a primary file or a secondary file. 


Since updating means getting a record from a disk file, changing some data, 

and putting the record back in its original location, an update file is like a com- 
bination input/output file. For this reason, the file to be updated must be speci- 
fied on both the Input and Output-Format sheets. Field locations should agree 
between the two sheets. Field names may vary depending on the updating being 
done. Field lengths must agree. 
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Example of Updating Records 


Periodically, you might want to update the accounting information for each cus- 
tomer in your customer file. You might also want to tag some customer records 
for deletion. A printed report, like the one shown in Figure 7, lists the updated 
information and the records tagged for deletion. 


The TRANS file contains two input record types. One type identifies disk rec- 
ords to be deleted (D in column 1); the other type contains information needed 
to update the MASTER file (3 in column 1). Figure 8 shows the RPG II coding 
necessary to update records and to tag records for deletion. 








Se eRageele ge ce crea PF PSE EOE FOES ‘pt aibve eve |8'6.9 a59'029°9°S 

rn a 3 2.2.8.7 8:2 0) Weed 4 3j6 7090 12 34 5'6 7,6 90 56|716 9 Of! 2134567 8)9 
CUSTOMER FILE LIS: Ses Penns os aerate, 

Fo. PUbHONE Rs le aa, Loney eae 7 CRED IT OVER SON oe. 

‘ Ae “CHARGES. |” CREDITS Qo dimiT | Lim 
WY YY DALY ever | eed” Decne 


¥ XXX XX XL XXX. KX XL XX. CRI . 
HARGE). | (CREDIT), | . aL) |, (CRLIMM eo... tented 










CUSTOMER FILE LISTING 





CUSTOMER CUSTOMER NEW CREDIT OVER 
NUMBER NAME CHARGES CREDITS PAYMENTS BALANCE LIMIT LIMIT 
136728 JONES VARIETY 5,000.00 3,000.00 1,500.00 500.00 1,000 
301628 JIM'S 5 AND 10 600.00 200.00 100.00 300.00 250 RATE 
795246 SCHMIDT HARDWARE 2,500.00 1,000.00 500.00 1,000.00 2,000 





Figure 7. Report of Updated Customer Records and Deleted Customer Records 
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Reorganizing a File 
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The space reserved for a file often becomes filled as additions are made. Reor- 
ganizing is a means of freeing space by physically removing inactive records 


(those with a delete code) from a file. 


You can reorganize your file using the Disk Copy/Dump program. The DELETE 
or OMIT parameter causes records of a specified type to be deleted from a file 

as it is copied. You can also use the Disk Sort program to remove the records 
tagged for deletion. For information on this program, see the /BM System/3 


Disk Sort Reference Manual, SC21-7522. 


Example of Reorganizing a File 


Records were tagged for deletion in the Example of Updating Records by placing 
a D in position 128. Now suppose you want to reorganize your customer file to 
physically remove these records from the file. You also want to print a report 
listing the customer records deleted (Figure 9). 


To delete these records you want to copy all records that do not have a Din 
Position 128. Figure 10 shows the RPG I! specifications necessary to reorganize 
the file. 


















'sislylsls!sis's'afa! 
23/4!5|6'718 9:0] 1 


ETED, CUSTOMER 


=o 


2'2/ 2/2 
12 3/4/5 


alsle 





ills 




























DELETED CUSTOMER LIST 






CUSTOMER CUSTOMER 















NUMBER NAME ADDRESS CITY/STATE 
652791 GREEN GROCERY, INC 1739-6TH ST SW BIG CITY, CALIF 
576290 STAR MARKET 3278 ADAMS ST GOODTOWN, GA 








Figure 9. Report of Deleted Customer Records 
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Chapter 2. Indexed Files 


An indexed disk file has two parts: an index and the records. The index contains 
the key field and disk address of each record in the file; it is organized sequentially 
by key field. Records in the file are organized in the order in which they are loaded. 
Records in an indexed file can be processed in the following ways: 


1. Sequentially by key. 

2. Sequentially within limits. 

3. Randomly by key or relative record number. 
4, Consecutively (without keys). 

5. By ADDROUT file. 


This chapter explains how to use the RPG !I language to create and maintain a 
single volume indexed file. Sample jobs are used to illustrate these functions. 


To understand the sample jobs, a basic knowledge of RPG II is necessary. If you 
do not fully recall some of the coding used in the sample jobs, you should refer 
to the /BM System/3 RPG I1 Reference Manual, SC21-7504 (for the Model 10 
Disk System or the Model 15), or the /BM System/3 Model 6 RPG I! Reference 
Manual, SC21-7517, depending on the system you have. 


CREATING AN INDEXED FILE 


You can create a single volume indexed file with records that are in ordered or 
unordered sequence. An ordered sequence means the records are arranged in 
order according to the major control field that will be used as the key of the file. 
If an ordered sequence is specified, records are sequence-checked by System/3 
data management. 


An unordered sequence means the records are in no particular order. For example, 
if records in an inventory item file were organized by frequency of use, they would 
be in an unordered sequence with the most active items at the beginning of the file. 
System/3 data management will not sequence check the records or check for dupli- 
cate records while an indexed file is being toaded in unordered sequence. The in- 
dex of an unordered file is sorted into ascending sequence after all the records have 
been loaded. At this time, System/3 data management will detect duplicate records. 


Note: Multivolume indexed files must be loaded in key field sequence, that is, 
in ordered sequence. See Related Publications in the Preface for sources of addi- 
tional information about multivolume files. 
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Creating an Ordered Indexed File 
To create an indexed file in an ordered sequence, you must make the following 
entries on the File Description sheet: 


File Description Specifications 


File Type 


19) ¥ 
of Record Address Fiel: 


Record Address Typ 


Type of Fite 
Filename Organization Device 


File Format or Additional Area 
Block 
Length 


8 9 1011 12 13:14 


Hl | | 
EEE 





The disk filename must be entered in columns 7 through 14. Column 15 must 
contain an O to indicate that the file is an output file. 


All records in a file must be the same length, so column 19 must contain an F to 
specify that the record length is fixed. 


A number equal to, or a multiple of, the disk record length must be entered in 
columns 20 through 23. This entry determines the size of the input/output area 
allocated by RPG II. (f you want block length calculated for you by RPG II, 
assign a block length equal to the record length. By blocking disk records, you 
can increase the input/output efficiency of your program by reducing the number 
of accesses. You must be sure, however, that enough main storage is available for 
your input/output area. 


Note: Block length calculation and input/output area allocation are described 
in /BM System/3 Disk Concepts and Planning Guide, GC21-7571. On Model 15, 
RPG I uses double buffering for indexed file output; therefore, main storage 
must be available for at least twice the block length plus twice the index buffer 
length. 


Columns 24 through 27 must contain the length of the disk record. Whenever a 
disk file is being described, DISK (Model 6, 10, 15), DISK40 (Model 12, 15), or 
DISK45 (Model 10, 12, 15) is required in the Device columns. 


Indexed files are allowed only on the main data area, and are not allowed on the 
simulation area. Models with 5445 or 3340 drives must use DISK45 and DISK40 
respectively. 


Entries in columns 31 and 32 indicate that an indexed file is to be created. An! 
in column 32 specifies an indexed file; an A in column 31 specifies that a key 
field exists. 


The other two entries describe the length and location of the key. Key length, 
entered in columns 29 through 30, is the same for all records in a file. The maxi- 
mum key length is 29 characters. The location of the first character of the key is 
specified in columns 35 through 38. Thus, if a 6-character key field were located 
in positions 73 through 78 of a disk record, you would enter a 73 in columns 37 
through 38 of the File Description sheet and a 6 in column 30. 
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Creating an Unordered Indexed File 


To create an indexed file in an unordered sequence, one entry is needed on the 
File Description sheet in addition to the entries needed to create an ordered 
indexed file. This entry is a U in column 66, indicating that the records are to be 
loaded in an unordered sequence: 


File Description Specifications 








< Audition/Unordered 
Length of Key Field or 
of Record Address F ielc 
Record Address Type 


Type of File . 
Filename Organization Device 


or Additional Area fx 





eles wba hee 
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Example of Creating an Indexed File 


Suppose you want to create an inventory file on disk and want to process the rec- 
ords in various ways (sequentially, randomly, within limits). An indexed file pro- 
vides this processing flexibility. Whether you load your records in an ordered or 
an unordered sequence depends on which sequence gives you the most processing 
efficiency. 


To create an indexed file, you must first determine the input record format and 
the output record format (Figure 11). The file is created by writing the inventory 
item data from the input records onto disk. Notice that the output record format 
provides space so additional information can be added to the record later if nec- 
essary. 


Figure 12 shows the RPG 1I coding necessary to create the indexed inventory file. 
The program will count the number of records loaded and print the total after the 
file has been created. 


Input Record 
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CODE Record identifying code (I) 
ITEMNO Item number 
COMCL Commodity class 
WHSE Warehouse location 
UOM Unit of measure 
UPRICE = Unit price 
UCOST Unit cost 
WGHT Weight 
COLOR Color 
NOHAND New on hand quantity 
OOHAND~ = Old on hand quantity 
ONORD Quantity on order 
ORDPT Order point 
LDATE Latest transaction date 
DESCR Description 

DELETE Output record delete code 
Output Record 
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Note: The input file need not be a card file. See 
How to Use This Manual, Note Concerning Examples 
at the beginning of this manual. 
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Figure 11. Input Record and Output Record Formats 
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Once a file is created, it usually needs to be maintained. File maintenance means 
performing those functions that keep a file current for daily processing needs. 


Four file maintenance functions apply to indexed fi 
1, Updating records. 
Adding records. 


Tagging records for deletion. 


Reorganizing a file. 


les: 
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Updating Records 


Many jobs require you to change certain data in a record. This function is called 
updating. You can update the records in one of three ways: 


1, Sequentially by key. 

2. Randomly by key. 

3. Sequentially within limits. 

Since updating means getting a record from a disk file, changing some data, and 
putting the record back in its original location, an update file is like a combination 
input/output file. For this reason, the file to be updated must be specified on both 
the Input and Output-Format sheets. Field locations should agree between the two 


sheets; field names may vary depending on the updating being done. Field lengths 
must agree. 
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Updating Records Sequentially by Key 


Records are usually updated sequentially by key when you want to update a large 
part of the file. To update records in this way, the following entries are required 
on the File Description sheet: 


File Description Specifications 





File Lype 


Length of Key Field or 


File Designation ot Record Address Field 







Record Address Type 
Type of Fite A 
Organization xi Device 
File Farmat or Additional Area $x$} 


Fitename 


Record 
Length Starting 








VO/U/C/D 
P/S/C/R/T/D 





SY? 8 9 101112 13 14 


‘MC 
NY 


Al] Pa TrEDrsK | 
ve if ID Sik 











Some of the entries are the same entries needed to create an indexed file and were 
discussed in this chapter under Creating an Indexed File. 


The two new entries are circled. Column 15 must contain a U to indicate that the 
file is an update file. Column 16 can contain either a P or an S depending on 
whether the file is a Primary or a secondary file. 


Example of Updating Records Sequentially by Key 
For examples of this kind of updating, see: 


© Updating Records, Example of Updating Records in Chapter 1. This coding 
applies if the necessary File Description sheet entries are made. 


®@ Adding Records, Example of Adding Records Sequentially by K ey later in this 
chapter. 


Updating Records Randomly by Key 


When an indexed file is updated randomly by key, input records are chained to the 
indexed file. Chaining means comparing the record key with the key in the index. 
If the keys are equal, the corresponding data record is made available. The data 


used as a record key in the chain operation can be a field in an input record or it 
can be created in your program. 


Records are read from the indexed file during the calculation phase of the program. 
Fields of records read from chained update files can be read during total calculations 
and updated during total output, or read during detail calculations and updated 
during detail output. Records may also be read during detail calculations from 
chained update files and updated during total output. 


When you update records randomly by key, entries must be made on the File 
Description and Calculation sheets. 
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One new entry is needed on the File Description sheet in addition to the entries 
needed to update a file sequentially by key. One of the previous entries also has 
to be changed. 


File Description Specifications 












file Type Mode of Processing 











Length of Key Field or 


Fite Designation of Record Address Field 


Record Address Type 









Type of File 









Filename Organization Device 


or Additional Area 





File Format 

















Biock 
Length 


Record 


Length 


Key Field 
Starting 
Location 


P/S/C/R/T/D 


B 9 10:11:42 13:14 415 





The changed entry is a C in column 16, which identifies the file as a chained file. 
The new entry is an R in column 28, indicating that the file is processed randomly 
by key. 


The following entries are needed on the Calculation sheet to describe the chain 
operation: 





International Business Machines Cort 


RPG CALCULATION SPECIFICATIONS 
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| 





Punching, Grapae Page 


| Instruction 
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i Punch 


Factor 1 Operaticn Factor 2 
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Factor 1 must contain the name of the field to be used during the search for a match 
in the index, CHAIN must be entered as the operation, and Factor 2 must contain 
the name of the update file. 


A resulting indicator should be specified in columns 54 and 55 to indicate whether 
the record to be updated is in the index. (If the indicator is omitted, you will get 
an error during compilation.) Refer to the /BM System/3 RPG I! Reference 
Manual, SC21-7504 for more information. When a match is found in the index, the 
disk address of the corresponding record is available. The desired record can then 
be located and read into storage. At that time the record can be updated. Your 
program can check to see if the required record is in the file by checking the 
specified resulting indicator. When the indicator is off, the record was found and 
can be updated; when the indicator is on, the record was not found. 
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Example of Updating Records Randomly by Key 
Suppose that whenever a transaction is made you want to update the item record 
in the inventory file. Since the transaction records are not in sequence, you will 
Process the file randomly by key. You might also want to tag some records for 


deletion while the file is being processed. 


Figure 13 shows the RPG II coding necessary to update the records and tag records 
for deletion. The TRANS file contains the update and deletion information. 


Refer to Appendix H for more information on blocking records when processing 
an indexed file randomly. 
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Figure 13 (Part 1 of 2). Updating and Deleting Records in the Indexed Inventory File 
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When a record is not found, the input 


ent input device is used, a different 
method of handling the record-not- 
found condition can be used, such as 
printing a special message or issuing a 
message to the input device. 
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Updating Records Sequentially within Limits 


See Chapter 4 in this manual for information on updating records sequentially 
within limits. 


Adding Records 


After a file is created, it is often necessary to add records to the file. For an 
indexed file, records can be added that contain keys which are: above the highest 
key presently in the file; below the lowest key presently in the file; or in between 
keys presently in the file. In any case, the added records are placed at the end of 
the records presently in the file. The index entry for each added record is written 
at the end of the current entries in the index area. After all records are added, 
the index is automatically sorted by the system. 


If many records are to be added to the file, the time required for the index sort 

can be decreased by allocating a special work file This requires no special RPG I 

coding but does require a special OCL statement. See the section concerning use of 
| OCL in the manuals listed in the Preface under OCL References for additional 

information and an example of this option. For a further discussion of indexed 

file performance considerations, see /BM System/3 Disk Concepts and Planning 

Guide, GC21-7571. 


You can add records to a file in one of two ways: 
1, Randomly by key. 


2. Sequentially by key. 


Adding Records Randomly by Key Using Chaining 


Records can be added randomly by key to an indexed file in two ways, either 
with or without chaining. 


Chaining means matching the record key of the record to be added with the 
keys of the index. This matching is done as a check to ensure that the record 
to be added is not a duplicate of a record already in the file. The data used as 
a record key in the chain operation can be either a field in an input record or 
it can be created in your program. 
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When adding records randomly by key using the chaining method, entries 
must be made on the File Description, Calculation, and Output-Format sheets. 


The special File Description entries are shown below: 


File Description Specification 


















File Addition/Unordered | 
Number of Tracks 


File Type | Mode of Processing 








Extent Exit 
for DAM 


Length of Key Field or 
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File Designation 













































































End of Fite for Cylinder Ovarftow. 
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or Additional Area Core index 
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Length Length 
Starting 
Location 
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Column 16 must contain a C to indicate the file is a chained file. An R in col- 
umn 28 indicates the file is processed randomly by key. Column 66 contains 
an A, indicating records are added to the file. The File Type entry (column 15) 
may be either | or U. The | entry indicates the file will be read, but the file will 
not be updated. The U entry indicates the file will be read and existing records 
will be updated. 


The following entries are needed on the Calculation sheet to describe the chain 
operation: 
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Resulting 
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Factor 1 i Operation Factor 2 
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Factor 1 must be the name of the field to be used in the search for a match in the 
index, CHAIN must be entered as the operation, and Factor 2 must contain the 
name of the file. 


A resulting indicator should be specified in columns 54 and 55 to indicate 
whether the record to be added is a duplicate of a record already in the file. The 
record key is used to find the index entry that contains the same key. If a dupli- 
cate is not found, the record can be added to the file. Your program can check 
for duplicates by checking the specified resulting indicator. If the indicator is 
off, do not add the record because it is a duplicate; if the indicator is on, the rec- 
ord can be added. 
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The entry on the Output-Format sheet is an ADD in columns 16 through 18: 
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This entry tells the system that the fields defined on the following specification 
lines constitute the record to be added to the file specified in columns 7 through 
14, 


Example of Adding Records Randomly by Key Using Chaining 


Suppose you want to add new inventory items to the indexed inventory file 
created in the Example of Creating an Indexed File. The new records are not 
in sequence. New record keys may be lower, between, or higher than keys 
presently in the file. 


Input and output records will be in the same format as the records used to 


create the file. A printed report (Figure 14) will list all the new records added 
to the file. 


il2}3/els|6 


3 TEM | 





06/18/70 NEW INVENTORY ITEMS 


ITEM WAREHOUSE UNIT 
NUMBER DESCRIPTION LOCATION PRICE 


413010 CHOO1 BOX 100A FLUSH 768 4.90 
412146 CH143 BREAKER 15A 913 89 
411126 1500 TWIN SOCKET B 493 da dee 





Figure 14. Report of New Items Added to the Inventory File 
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Figure 15 shows the RPG I! coding necessary to add records to the inventory 
file and print the report. 
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Figure 15 (Part 1 of 3). Adding Records to the Indexed Inventory File 
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Figure 15 (Part 2 of 3). Adding Records to the Indexed Inventory File 





Indexed Files 41 





IBM 
RPG 


Date 


Program 





Programmer _ 


Punching 
Instruction 


International Business Machines Comeraton 


OUTPUT - FORMAT SPECIFICATIONS 


Vorapnic To oP 7 7] 
[— + . + : 
1 Punch po NF ! 
tee i Pf Is zl 


Form X21-9090 
Printed in U.S.A 


7576 77 7B 19: BU 
Program flee] i eae 


! 
identification ete *| ‘ 





















































































































device is used, a different method of handling 
error records can be used, such as printing a 


z i 
iz Space Skip Output Indicators See ae a a ~ Edit Codes “T 
5 eres —— fa? eh, a 
é | comme |e noun | ow | Ee pee | set 
Filename a 7 Field N. ee € i , aan * 7 i SY Date } Sign 
7 els And And epee Bh poate: |S | 2 ies : ae ; Fiela bunt | Position 
> =|2 " Set in S | Ne Yes 7 3 c | i? © Zero | 
FE 21a Els 5 | 3| 8)<] ouput 3 1 No No. | 4 DEM 4. Suppress. | 
£ g £ < 2 | Bp 1 2 5 € Record & “S a ss a 
* - 3 | | wo} ao Constant or Edit Word 
7 8 9 10 11:12 13 14/15 }16]17 19 20}21 22)23 Ae: 26 |27) 28 7920.3 31132 33 34 35 36 37438 439 40 41 42 43 7 45 46 47 48 49 50 51 5? 53 94 55 5A 5? 5B OOO GO 61 62 64 64 6S 6H G7 68 69 TOL/T 12 14 14 
T TTT Tr Ale Tt T ToT T 
eT es TTT Ty] Cosi’ 1 Pei eee de 
Pee || hone ‘HAND Bh roasts Nai ae tala! 
: reid ns Te Pi ie rece bere Thane ole Aelak sie eb te ares ee 
bit: Lf fe | Pits ‘ORDER’. | vb 
bp + % ele a me tf : : : ee 
oO J } ' 99 ! | ' t 
i t ' : ot { a 4 | OE a + ‘ 4 
oO | a4 i i |TEMNO i i ' ! | i i 
| : ; Wt I mappa fend: 
9 oe tiie) Margen a 8 : i 
bitte ao ' | ia ay ae 
Oh Lae | | HSE | ! vie a fd 
tobe fps | : ios ' : i: ‘ | 
She ead | | BARC ce Se dvew ope 
i : : aes .: ‘ i : par 
| un so pee ek pede! | 
: O bite | i ; 
& fo NOK i - 1 + rye + i t t + 4 
' -1. f ek i , ete 4 1 ae t 4e4 
j oui Z| | i : ; : | fs 
t tc by 
RECORDS, avveD) dna ealNg 
1 | ' 1 i 
fi : 1 if | 
‘DUPLICATES Ascii a oe Es ea he 
Since a card file is used for input, error records are 
5 handled by being selected to stacker 3; correct 
records are selected to stacker 1, If another input 


special message. 
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Adding Records Randomly by Key Without Chaining 


Chaining is not necessary if no checking is to be done by the program for 
duplicate records and the file is not being read or updated. (The system will 
check for duplicate records and return a halt if duplicates exist, even if chaining 
is not done.) In this method, the indexed file is defined as an output file and 
records to be added are read from a separate file (or generated in the program) 
and written out to the indexed file. The added records are placed at the end of 
the file. After the program has finished, the index is sorted into key field se- 
quence. Records added in this manner may: 


1. Contain keys that are above the highest presently in the file. In this case, 
the records constitute an extension of the file. 


2. Contain keys that are either lower than the lowest presently in the file, 
or fall between those already in the file. 


The File Description entries characteristic of this method of adding records to 
an indexed file are: 
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For an example of this kind of add, see Adding Records, Example of Adding 
Records to the End of the File in Chapter 1. The coding used in that example 
applies if the preceding File Description entries are used for the disk file. Use 
06 for length of key field (columns 29 and 30); enter 3 in column 38 for key 
field starting location. 


Indexed Files 43 


Page of GC21-7566-1 
Issued 24 September 1976 
By TNL: GN21-5427 


Adding Records Sequentially by Key 


Records added to an indexed file sequentially by key (either single volume 
or multiple volumes) must either: 


1: Be added between existing records (that is, the key of the record being added 
must be lower than che last key retrieved and higher than the preceding key) 
or 


2. Have keys that are higher than existing keys in the file (that is, the indexed 
file is at end of file). 


The unshaded columns on the File Description and Output-Format sheets below 
indicate entries that must be made to add records sequentially by key. Some of 
the File Description entries are also used to create an indexed file; these entries 
are discussed under Creating an Indexed Fife, previously in this chapter. 
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The File Type entry (column 15) can contain either an | or a U. The | entry indi- 
cates that the file will be read, records will be added, but no updating will be done. 
The U entre indicates that records will be read and updated and new records will 
be addec. 


Two special entries are needed 10 add records, one on the File Description sheet 
and one on the Output-Format siieet. These entries are circled. 


The entry on the File Description sheet is an A in column 66. This entry tells the 
system that records will be added to the file described on this line. 


The entry on the Output-Format sheet is an ADD in columns 16 through 18. This 
entry tells the system that the fields defined on the following lines constitute the 
records to be added to the file specified in columns 7 through 14. 


Records might be added sequentially to an indexed file in situations where the 
activity of the file is high and the records to be added have been previously sorted 
into ascending sequence by key field. Adding sequentially in this kind of situation 
can result in better performance than adding records randomly with chaining by 
allowing large blocking factors. 


Example of Adding Records Sequentially by Key 


Suppose you want to add new inventory items to the indexed inventory file 
created in Example of Creating an Indexed File, previously in this chapter. The 
new item records are merged with records of receipts of existing items; thus, 
existing inventory records are updated and new records are added during the 
same program run. The activity of the inventory file (number of transactions 
against the file) is high, so the transaction file, containing new items and receipts, 
is organized into ascending sequence by item number (key field), enabling the file 
to be processed sequentially by key. Input records for new items are in the same 
format as the inventory records. 


Figure 16 shows the coding to update the inventory file and to add new item rec- 
ords to the file. At the same time, a list of new inventory items is printed, similar 
to the list produced in the example of adding records randomly to the inventory 
file (Figure 13). 
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Figure 16 (Part 1 of 4) Adding Records Sequentially by Key 
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Tagging Records for Deletion 


When a record becomes inactive, you probably will not want to process it with the 
other records. Since the record might not be physically removed from the file, how- 
ever, you must identify it so it can be bypassed. One way to identify the record is 
to put a code, called a delete code, in a particular location in the record. This code 
can be any character you want. Any program which should not process deleted 
records can check for this code. If the code is present, the program bypasses the 
record. The deleted records can be physically removed from the file by reorganiz- 
ing the file (see Reorganizing a File in this section). 


Example of Tagging Records for Deletion 


An example of tagging records for deletion is shown in this section under Updating 
Records, Example of Updating Records Randomly by Key. 


Reorganizing a File 


Reorganizing a file is similar to creating the file. Reorganization may be necessary 
for two reasons: 


1. To increase processing efficiency. 
2. To free disk space. 


You can increase processing efficiency by restoring your file to its original sequence. 
When you add records to a file, these records are added at the end of the records 
already in the file; however, the keys are always in order in the index. When the file 
is processed sequentially by key, the disk access arm moves back and forth between 
the sequenced records (those originally created) and the added records. This increases 
processing time. 


Disk space can be made available by removing inactive records during a file copy. 
All records with a delete code can be physically deleted from the file. 


If you want your file in an ordered sequence, you can reorganize the file to place 
the added records in sequence with the records originally created and remove rec- 
ords tagged for deletion. To reorganize the file in this manner, you can use the {BM 
Disk Copy/Dump program. For an explanation on how to use this program, see the 
IBM System/3 Model 10 Disk System Control Programming Reference Manual, 
GC21-7512, the /BM System/3 Model 15 System Contro! Programming Reference 
Manual, GC21-5077, or the /BM System/3 Model 6 Operation Control! Language 
and Disk Utility Programs Reference Manual, GC21 -7516, depending on the system 
you have. 


If you want your file in an unordered sequence and want only to delete records in 
the file, you can also use the IBM Disk Copy/Dump program. 


When you want to change the order of the records and maintain an unordered se- 
quence, you must determine what method can be used to produce the file in the 
required order. For example, if a count of activity was maintained in each master 
record, the file could be sorted in descending sequence on this activity field, then 
reloaded as an indexed file. This would place the most active records at the front 
of the file. 
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OTHER WAYS TO PROCESS INDEXED FILES 


Processing an Indexed File Consecutively 


An indexed file may be processed consecutively (read only) by defining the indexed 
file as a sequential input file in the File Description Specifications. When an indexed 
file is processed consecutively, the file index is bypassed and data records are read 
consecutively from the beginning of the file to the end, exactly as a sequential file. 
Indexed files may not be created, added to, or updated consecutively. 


Consecutive processing of an indexed file is useful, for example, for reading records 
from an indexed file when the file index is unusable for some reason. 


Processing an Indexed File Randomly by Relative Record Number 


An indexed file may be processed randomly by relative record number if the file 

is an input file. The file must be described as a sequential file (that is, columns 31 
and 32 must be blank) and must be described as a chained file (C in column 16 of 
the File Description sheet). The CHAIN operation code must be used in calcula- 
tions to read records from the file. Records may not be updated, added, or written 
out to an indexed file using this method. 


Random processing of an indexed file by relative record number can provide im- 
proved performance over random processing by key, because the file index need not 
be read. However, it is the user’s responsibility to ensure that records in the indexed 
file are properly sequenced for this type of processing. 


Chapter 3. Direct Files 


A direct file is one in which records are assigned specific record locations on disk. 
Direct file organization enables the program to access any record i the tile with- 
out examining other records or searching an index. 


This chapter explains how to use the RPG II janguage to create and maintain a 
direct file and to retrieve records from the file. Sample jobs illustrate these func. 
tions. 


To understand the sample jobs, a basic knowledge of RPG II is necessary. If you 
do not fully recall some of the coding used in the sample jobs, refer to the ‘BM 
System/3 RPG I! Reference Manual, SC21-7504 (for the Model 10 Disk System 
or the Model 15), or the /BM System/3 Model 6 RPG I! Reference Manual, 
$C21-7517, depending on the system you have. 


CREATING A DIRECT FILE 


To create a direct file, you must define a disk file as a chained output file. The 
following entries are needed on the File Description sheet to describe various 
characteristics of the disk file: 


File Description Specifications 


tile Type 


File Designation 


Fitename Device 


File Format 


Q 
g 
Sle 
g 





The disk filename must be entered in columns 7 through 14; column 15 must con- 
tain an O, and column 16 a C, indicating that the file is a chained output file. 


All records in the file must be the same length. Thus, column 19 must contain 
an F to specify that the record length is fixed. 


A number equal to or a multiple of the disk record jergth must be entered in 
columns 20 through 23. This entry determines the size of the input/outpit area 
allocated by RPG !I. For an explanation on block iength: calculation, see the 

/BM System/3 Disk Concepts and Planning Guide, GC21-7571. tf you want 
block length calculated for you by RPG II, assign a block length equal to the rec- 
ord length. By blocking disk records you can increase the input/output efficiency 
of your program by reducing the number of accesses. You must be sure, however, 
that enough main storage is available for your input/output area. 
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Columns 24 through 27 must contain the length of the disk record. Column 28 
contains an R to indicate that random processing is to take place. Whenever a disk 
file is being described, DISK (Model 6, 10, 15), DISK40 (Model 12 or 15), or DISK45 
(Model 10, 12, or 15) is required in columns 40 through 46. 


Relative record numbers are always used with the CHAIN operation code in your 
program to make the corresponding record locations in a direct file available for 
loading. The data used as a relative record number in the chain operation can be 
either a field in an input record or it can be created in your program. To use the 
chain operation, you must make the following entries on the Calculation sheet: 
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‘rumog foo! [TY 1 TT] re 
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Resulting 


Indicators 


Factor 1 Operation Factor 2 


18 19 20 21 22 23 24 2 26 2/|28 29 30 34 32/33 34 35 36 37 3B 39 40 41 42 


Factor 1 must contain either the name of the field containing the relative record 
number or the relative record number itself. CHAIN must be entered as the opera- 
tion, and Factor 2 must contain the name of the file to be loaded. 


A resulting indicator should be specified in columns 54 and 55 with the CHAIN 
operation. If the record is not found (that is, the record location does not exist in 
the file) the indicator specified in columns 54 and 55 is turned on. This situation 
can occur either when the relative record number is higher than the highest record 
location in the file or when the relative record number is invalid for some other 
reason. If an indicator is not specified in columns 54 and 55 and the record is not 
found, the program halts. 


When a direct file is loaded as a chained output file, disk system management 
clears the entire file area to blanks before records are loaded. Thus, if a record is 
not loaded, the space reserved for it remains blank. Programs written to access 
records in the direct file should check each record for blanks before attempting to 
process it, since the record may not have been previously loaded. 


The method you use to write data records on the file depends on whether you must 
check for synonyms among those records. Synonyms are two or more records whose 
control fields yield the same relative record number. For more information on syn- 
onyms, see the /BM System/3 Disk Concepts and Planning Guide, GC21-7571. 


Creating a Direct File without Synonyms 


A direct file can be created without synonyms when the relative record number 
either corresponds to a field containing sequential values or is derived in such a way 
that no synonyms are produced. 


When you do not have synonyms, you can load records into a direct file in a single 
pass. You do this by specifying a chained output file and writing records in the file 
by means of the chain operation. Record locations cannot be inspected before they 
are filled with data. If a synonym is encountered, it is written over the previous 
record. The previous record is lost. 


Example of Creating a Direct File without Synonyms 


Suppose you want to create a customer file on disk. The following are significant 
characteristics of the file: 


@ Customer numbers are assigned on a sequential basis; new customers are 
assigned the next higher number. 


® Deletions from the file are few. 


@ The file will be used to process invoices, orders, and cash payments in a random 
manner. 


@ The file must allow direct inquiry to any customer’s record. 


@ The file has low activity; for example, out of 5000 customer records, only 100 
invoices are processed per day. 


You need both the direct and consecutive processing capabilities offered by indexed 
and direct file organizations. Because the customer numbers are assigned consecu- 
tively, synonym records are not a consideration. For this reason, and because there 
will be few deletions from the file creating wasted space, direct file organization 
provides maximum flexibility and access speed. 


Your first step, then, is to create the direct file. The record format shown in Figure 
16 satisfies your information needs. Additional fields in the record will contain 
information to be used in specific jobs, such as customer payments, invoicing, and 
sales analysis. (Various applications using the customer file are described later in 
this chapter.) 


The file is created from data on input records (Figure 17). The customer number 
(CUSTNO) is used as the relative record number to chain to the direct file. The 
customer data from the input records is then written on disk. Each record written 


on disk is also printed in the report shown in Figure 18. 


Figure 19 shows the RPG I} coding necessary to create the direct customer file. 
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ZIP Zip code 
DELETE Output record 
delete code 


18M 3700 





Note: The input file need not bea card file. See 
How to Use This Manual, Note Concerning Examples 
at the beginning of this manual. 


Output Record 












CUSTNO SLSMN# CUSNAM 


TRRTRY 







Re 301 


CTYSTA ZIP 


62 63 67 68 228 


Reserved space for 
record expansion 








DELETE 


Figure 17. input Record and Output Record Formats 
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CUSTOMER TYPE NAME ADDRESS ZIP CODE TERRITORY SALESMAN 


1637 B JONES VARIETY 14 S MAIN BEDROCK, TEX 45412 12 015 
4301 B JIM'S 5 AND 10 1103 FRANKLIN ST GLENCOE, MN 55336 12 O15 
3601 D SCHMIDT HARDWARE 600 1ST ST NW HILL CITY, MD 21222 02 046 





Figure 18. Report of Customer Records 
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Figure 19 (Part 1 of 2). Creating a Direct Customer File 
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Creating a Direct File with Synonyms 


If you have synonyms, you can create a direct file by using more than one job to 
load records into the file. The exact method you use depends on how you plan to 
handle synonym records. Your first job must define the disk file as a direct output 
file, causing disk system management to clear it to blanks. Since blank record 
locations indicate an unused location, clearing the file to blanks is necessary to en- 
sure that no unwanted characters are left in the file area. Once the file has been 
cleared, one or more subsequent jobs can be run using the update function to read 
record locations and check for synonyms while loading the file. 


Figure 20 shows a method of defining a direct file and clearing it to blanks. In 
this method, the input record file from which the direct file is created is placed in 
the MFCU; another type of input, such as a sequential disk file, could be used. 
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Figure 20 (Part 2 of 2). Defining a Direct File and Loading Only the First Record 


The disk file, which is specified as a chained output file, is cleared to blanks by disk 
system management after the job begins. The CHANUM field from the input file is 
used to chain to the corresponding location in the direct file, and the first record is 
placed in the file. The last record (LR) indicator is then turned on by a SETON 
operation, forcing the end-of-job condition. The direct file now contains a single 
record. This job can be immediately followed by one or more jobs which read the 
remaining records from the MFCU and write out the disk records, using the update 
function. 


After your direct file is defined and cleared to blanks, different steps are required 


to put records into the file, depending on the method you use to handle synonyms. 


There are several ways to handle synonyms. Two of the most common methods 
are: 


1. Storing all synonyms in an area of the file set aside for them. 


2. Storing synonyms in unused record locations between the records in the file. 
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If the first method is used, all records can be placed in the direct file in a single job. 
That job would retrieve and check each record location before it is filled. If the 
location already contains a record (that is, the record to be written is a synonym), 
the synonym is stored in the next available location in the part of the file set aside 
for synonyms. Thus, all home records and synonyms are placed in the file ina 
single job. A home record is the first synonym record; it is stored in the record 
location indicated by its relative record number. The rest of the synonyms are then 
linked together so they can all be found by locating the home record. For more 
information, see the /BM System/3 Disk Concepts and Planning Guide, GC21-7571. 


If the second method is used, two jobs are required to place home records and syn- 
onyms in the direct file. The first job loads all home records; synonyms are by- 
passed. The second job loads synonyms in the record locations available between 
home records. Both jobs are done using the update function to check each record 
location. 


Whatever method you use to handle synonym records, you will have to devise a 
sequence of jobs similar to those just described. Remember: 


1, You load a disk file as a direct file by specifying a chained output file. 


2. In order to check for synonyms, you must use the update function. Random 
update with a direct file is described later in this chapter. 


RETRIEVAL OF RECORDS IN A DIRECT FILE 


Record retrieval is used when you want to get information from a record, but do 
not want to modify the record. You would normally use this method when you 
want to get data from a record to produce a report. Record retrieval can be done 
either consecutively, randomly by relative record number, or randomly by 
ADDROUT file. For a discussion of record retrieval done randomly by ADDROUT 
file, see Chapter 4 in this manual. 


Consecutive Retrieval 


Consecutive retrieval of records from a direct file requires the following entries on 
the File Description sheet: 


File Description Specifications 





File Type 


Fite Designation 


Filename Device 


File Format 


Block 
Length 


o 
= 
g 
> 
o 


& 








Some of these entries are the same ones needed to create a direct file and were dis- 
cussed in this chapter under Creating a Direct File. 


The new entries are circled. An 1 is entered in column 15 to indicate that the file 
is an input file. Column 16 can contain either a Por anS depending on whether 


the file is a primary or secondary file. Because the file is an input file, it must also 
be defined on the Input sheet. 


Direct Files 61 


Example of Consecutive Retrieval 


Suppose you want to process the direct customer file, CUSTFILE, created in the 
Example of Creating a Direct File without Synonyms, to produce a monthly report. 
This report lists all customers that have had no sales activity during the period. This 
report is analyzed by sales personnel, who then make follow-up calls. Since all the 
customer records will be checked and since the file is in sequence by customer num- 
ber, the report is produced by consecutive processing of the direct file. 


The format of the disk records in CUSTFILE is shown in Figure 21. Figure 22 
shows a part of the report produced by the consecutive processing job. The report 
consists of fields selected from CUSTFILE and an accumulated total for accounts 
receivable (TOTAR). 


Figure 23 shows the specification sheets necessary to consecutively retrieve records 
from CUSTFILE to produce REPORT1, which is a list of recently inactive customers. 


Since the direct file probably contains blank record locations and inactive records, 
a technique is employed on the Input sheet to bypass such records (Figure 23). If 
a method is not used to bypass unidentified records, the program halts when they 
are encountered. 
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IDCODE Identification code LSTORD Last order date 

CUSTNO Customer number LSTPAY = Last pay date 

TYPE Type THSPER = Charges for this period (month) 
TRRTRY Territory LSTPER = Charges for last period (month) 


SLSMN# = Salesman number ARLT30 = Accounts receivable for less than 30 days 
CUSNAM Customer name AR3060 Accounts receivable for 30 to 60 days 
ADDR Customer street address AR6090 Accounts receivable for 60 to 90 days 
CTYSTA = City and state AROV90 Accounts receivable for over 90 days 

ZIP Zip code DELETE Delete code 

CREDIT Credit code 





Figure 21. Disk Record Format for the Direct Customer File 
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CUSTOMER NAME: CITY,STATE SALESMAN LAST ORDER SLS PREV PER CRDT TOT A/R 


1637 JONES VARIETY BEDROCK, TEX 15 4/13/71 240.07 OL - 00 
2279 GREEN GROCERY, INC BIG CITY, CALIF 102 4/27/71 1,200.00 Ol 600.00 
2331 STAR MARKET GOODTOWN, GA 74 4/01/71 31.95 03 937.16 


ee 


Figure 22. Report of Inactive Customers in the Direct Customer File 
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Figure 23 (Part 2 of 2). Consecutive Retrieval of Inactive Customers in the Direct Customer File 
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Random Retrieval 


Random retrieval of records from a direct file requires the following entries on the 
File Description sheet: 


File Description Specifications 








File Type Mode of Processing 





Fite Designation 


Filename : 4 Device 


File Format 





Block Record 
Length Length 





VO/Uv/C/O 





R78 9 10 11 12 13 


Spree 


0 41 42 43 44 45 46) 


Some of these entries are the same ones needed to create a direct file and were dis- 
cussed in this chapter under Creating a Direct File. 


The circled entry, an | in column 15, is new. This entry indicates the file is an input 
file. 


The records in the direct file to be retrieved must be further described on input 
specifications. On the Input sheet, a direct file being retrieved must have an alpha- 
betic sequence entry (columns 15-16), because sequence checking cannot be done 
for chained files. 


If the direct file being retrieved contains synonym records, calculations must be 
included in the program to test for synonyms and retrieve the desired record. The 
CHAIN operation code must be specified on the Calculation sheet to randomly 
retrieve records from a direct file. The entries on this sheet are the same ones dis- 
cussed in this chapter under Creating a Direct File: 
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Example of Random Retrieval 


Suppose the direct customer file, CUSTFILE, created in the Example of Creating 
a Direct File without Synonyms and processed consecutively in the Example of 
Consecutive Retrieval, is to be retrieved randomly. You want to make demand 
inquiries each day concerning customer sales and account information. Inquiries 
are received for records containing an | in column 1 followed by the customer 
number of the record to be retrieved (Figure 24). Inquiry records are read from 
the primary MFCU hopper in this example; substitute devices such as console/ 
keyboard devices, can also be used. When an inquiry record is read, the customer 
number (CSTMER) is used as the relative record number to chain to CUSTFILE. 


The format of the disk records in CUSTFILE is the same as the disk record format 
used in the consecutive retrieval example. 


If a record that corresponds to the number on the inquiry record is found in 
CUSTFILE, a response is printed in the format shown in Figure 25. This response 
lists pertinent sales information and the total accounts receivable amount. 


The RPG II coding for the random inquiry application is shown in Figure 26. 


yore ID Code 


CSTMER 


Figure 24. Inquiry Record Format 












CUSTOMER ACTIVITY SALESMAN CREDIT LAST ORDER LAST PAY SLS THIS PER SLS LAST PER TOTAL A/R 


S119 A 105 ol 4/17/71 4/01/71 360.00 239.50 360.00 
6678 RECORD NOT FOUND--INVALID RECORD NUMBER 
1703 I 3:5) 03 11/19/70 12/01/70 -00 -00 -00 


i a pie 


Figure 25, Printer Output from Random Inquiry Requests 
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Figure 26 (Part 1 of 2), 
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MAINTAINING A DIRECT FILE 


After a file is created, file maintenance is usually necessary to keep the file current. 
Three file maintenance functions apply to direct files: 


1. Adding records. 
2. Tagging records for deletion. 


3. Updating records. 


Adding Records 


Unlike sequential and indexed files, direct files can have space available between 
records for new records to be added. Records are added to a direct file by anor- 
mal update operation (either consecutive or random processing) as follows: 


1. The relative record number is developed for the record to be added. 

2. The location is read into main storage. 

3. If the location is blank, the new record can be stored. 

4. If the location is occupied, and the program can handle synonyms, the new 


record can be stored as a synonym. 


For a discussion of the entries needed to add records consecutively, see Updating 
Records, Consecutive Updating of Records in this chapter. For a discussion of 
the entries needed to add records randomly, see Updating Records, Random Up- 
dating of Records in this chapter. 


If records must be added but the allotted file space is full, you must increase the 
total space available for the file. The Disk Copy/Dump program can be used to 
copy the file into a larger area. For an explanation on how to use this program 
to copy the file, see the /BM System/3 Model 10 Disk System Control Program- 
ming Reference Manual, GC21-7512, the /BM System/3 Model 15 System Con- 
trol Programming Reference Manual, GC21 -5077, or the /BM System/3 Model 6 
Operation Contro! Language and Disk Utility Programs Reference Manual, 
GC21-7516, depending on the system you have. 


Tagging Records for Deletion 


Like sequential and indexed file records, direct file records can be identified for 
deletion by a delete code. This code is usually a single character at a particular 
location in the record. When the file is processed, your program must check for 
the delete code; if the code is present, the record can be bypassed. 


Since the record has a delete code, the record location is available for a new 
record. Either a synonym for a different location can be stored there, or the 
location can be reused by assigning the relative record number to a new record. 
If the file contains synonyms, be careful not to delete synonym linkage inform- 
ation when you delete a record and reuse the location. 
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Another method of deleting records, which may sometimes be preferable to 
using a delete code, is to restore the record location to blanks. A blank record 
in a direct file is an available record. 


You cannot delete records from a direct file by using the Disk Copy/Dump pro- 
gram. Because the DELETE parameter of the COPYFILE control statement 
causes physical deletion of identified records, the DELETE parameter would 
destroy the relative positions on which direct file organization depends. 


Example of Tagging Records for Deletion 


You tag direct file records for deletion in the same way as sequential or indexed 
file records. For an example of this method, see the examples of tagging records 
for deletion in Chapters 1 and 2. 


Updating Records 


To modify certain data in the disk records, you must use the update function. 
Updating means getting a record from a disk file, changing some data, and putting 
the record back in its original location. Thus, an update file is like a combination 
input/output file. 


The file to be updated must be specified on both the Input and Output-Format 

sheets. Field locations should agree between the two sheets. Field names may 

vary depending on the updating being done. Field lengths must agree. 
eS 
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Records can be updated either consecutively or randomly. 
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Consecutive Updating of Records 


If all or most of the records in a direct file are to be processed, you may want to 
update the file consecutively. Consecutive updating of records in a direct file 
requires the same File Description entries as consecutive retrieval of a record, with 
one exception: column 15 must contain a U to indicate that the file is an update 
file: 


File Description Specifications 





File Type 


File Designation 


Filename Device 


File Format 


Block 
Length 











Example of Consecutive Updating 


Suppose the direct customer file created in the Example of Creating a Direct File 
without Synonyms and retrieved consecutively in the Example of Consecutive 
Retrieval is to be updated. At the end of each sales period, when all reports are 
completed, the sales figures for that period must be adjusted. Sales amounts for 
the last period (LSTPER, Figure 21) are replaced by sales amounts from the cur- 
rent period (THSPER). The field containing the current sales amount is reset to 
zero, ready to accumulate the sales amount for the next selling period. Fields 
containing overdue amounts will be updated when the monthly accounts receiv- 
able statements are written. 


Figure 27 shows the coding necessary to consecutively update CUSTFILE. As 
an update file, CUSTFILE must be defined by file description specifications, 
and the fields to be updated must be described by input and output specifica- 
tions. Customer records are read, updated, and written out in the order they 
are stored in the direct file. 
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Figure 27 (Part 1 of 2). Consecutive Updating of Records in the Direct Customer File 
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Figure 27 (Part 2 of 2). Consecutive Updating of Records in the Direct Customer File 
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Random Updating of Records 


Random updating of records in a direct file requires the same File Description 
entries as random retrieval of a record, with one exception: column 15 must con- 
tain a U to indicate that the file is an update file: 


File Description Specifications 





File Type 


File Designation 


Filename 


File Format 


F/V/S/M/O. 
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'f the direct file being updated contains synonym records, calculations must be 
included in the program to test for synonyms and locate the desired record. 
Thus, the CHAIN operation code must be specified on the Calculation sheet. 


The entries on the sheet are the same ones discussed in this chapter under Creating 
a Direct File: 
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Example of Random Updating 


Each day you want to prepare invoices for customer orders for the file described 
in the Example of Consecutive Retrieval. \nformation from the invoices is used to 
update the customer file, CUSTFILE. Since this information is read from records 
(Figure 28) in an unordered manner, a random update job is required. 


The input records contain the date and total amount of the transactions for each 
customer. New addresses are also on this record when required. As each record 
is read, the customer number (CUSTMR) is used to chain to the direct file. The 
amount of the transaction is added to total sales for the period {THSPER) and to 
the accounts receivable amount (ARLT30). The transaction date is placed in the 
date of last order field (LSTORD) in the customer record. 


If an address change is indicated (an X in column 18 of the input record), the new 
customer address replaces the old. If a record is not found in CUSTFILE because 
of an invalid relative record number, the input record is printed, followed by the 
statement “Above record not found—invalid customer number.” 


CUSTFILE, described as a chained update file, must be described on both {Input 
and Output-Format sheets because data is read from and written on the file. The 
specifications are shown in Figure 29. 
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CUSTMR Customer number 


DATE Date 

TOCOST = Total transaction amount 
NEWADR New address code 
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Figure 28. Daily Invoicing Record 
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Figure 29 (Part 1 of 2). Random Updating of Records in the Direct Customer File 
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Figure 29 (Part 2 of 2). 
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Chapter 4. Record Address Files 


Record address files are input files that indicate (1) which records are to be read 
from disk files and (2) the order in which the records are to be read from the disk 
file. There are two types of record address files: 


1. Files containing relative record numbers. 
2. Files containing record key limits. 


This chapter explains how to use the RPG II language to process these two types 
of record address files. Sample jobs are used to illustrate the functions. 


To understand the sample jobs, a basic knowledge of RPG II is necessary. If you 
do not fully recall some of the coding used in the sample jobs, you should refer 
to the /BM System/3 RPG I! Reference Manual, SC21-7504 (for Model 10 Disk 
System or the Model 15), or the /BM System/3 Model 6 RPG |/ Reference Man- 
ual, SC21-7517, depending on the system you are using. 


FILES CONTAINING RELATIVE RECORD NUMBERS (ADDROUT FILES) 


A record address file that contains relative record numbers is called an ADDROUT 
file. ADDROUT files are comprised of 3-byte, binary, relative-record numbers 
that indicate the relative position (first, twentieth, ninety-ninth, etc.) of records 

in the file to be processed. 


An ADDROUT file can only be a disk file. All types of file organization (sequen- 
tial, indexed, or direct) for Primary or secondary files can be processed by an 
ADDROUT file. When an RPG II Program uses an ADDROUT file to process a 
file, it reads a relative record number from the ADDROUT file, then locates and 
reads the record situated at that relative Position in the file being processed. Only 
records with relative record numbers in the ADDROUT file are processed. 


Creating an ADDROUT File 


An ADDROUT file is created by the Disk Sort program. For an explanation on 
how to create an ADDROUT file, see the /BM System/3 Disk Sort Reference 
Manual, SC21-7522. 
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Processing by an ADDROUT File 


To use an ADDROUT file to process a file in an RPG II program, entries must be 


made on the File Description and Extension sheets. Input specifications are not 
required. 


File Description Specifications 


The File Description sheet must describe both the file to be processed and the 
ADDROUT file. The description of the file to be processed must contain the 
following entries in addition to the usual entries necessary to describe the file: 


File Description Specifications 


Mode of Processing 





Column 28 must contain an R to indicate that the file is to be processed randomly. 
Column 31 must contain an | to indicate that the file is to be processed by relative 
record numbers from an ADDROUT file. 


The ADDROUT file must be described with the following entries: 


File Description Specifications 
















File Type 


Length of 
of Record Address Field 





Fite Designation 





Record Address Type 


Type of File 
Organization 







Filename Device 





File Format 





Block Record 
Length Length 


Extension Code E/L 


(/O/U/C/0 
F/VIS/M/D 








S378 9 10 1112 1314 


a 


The ADDROUT filename must be entered in columns 7 through 14. Column 15 
must contain an | to indicate that the file is an input file. Columns 16, 31, and 
32 contain an R, |, and T respectively; these three columns indicate that the file 
is a record address file consisting of relative record numbers. 


Because all records in a file must be the same length, column 19 contains an F to 
indicate that the record length is fixed. 
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The record length (columns 24 through 27) and the length of the record address 
field (columns 29 through 30) are always 3 because the ADDROUT file consists 
of 3-byte, relative record numbers. The block length should be equal to or a 
multiple of the record length. 


Whenever a disk file is described, DISK (Model 6, 10, 15), DISK40 (Model 12 or 15), 
or DISK45 (Model 10, 12, or 15) is required in the Device columns. Since the file must 
be further defined on the Extension sheet, column 39 must contain an E. 


Extension Specifications 


Two entries are needed on the Extension sheet if you want to process by an 
ADDROUT file: 
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Maa etten ae eh ts ol Extension Specifications 


Ter Filename 


From Filename 
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Columns 11 through 18 must contain the name of the record address file. This 
name must be the same one given to the record address file on the File Descrip- 
tion sheet, 


Columns 19 through 26 must contain the name of the file to be processed. This 
name must be the same filename defined on the File Description sheet. This 
entry indicates that the file is to be processed by the ADDROUT file coded in 
columns 11 through 18. 

Example of Processing by an ADDROUT File 
You have a customer master file containing: 
@ Customer numbers and addresses 
@ Salesman numbers 
@ Accounts receivable amounts 
The file is an indexed file processed by customer number. It is processed through- 
out the month for invoicing and at the end of every month for customer statements. 
Along with the monthly statements, the sales department wants the accounts receiv- 


able, printed by customer number within salesman number, for al! customers owing 
more than $2500.00. 
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In order to do this, the records of customers who owe more than $2500.00 must 
be sorted according to salesman number. You sort the file using an ADDROUT 
sort because there is not enough disk storage to use a tag-along sort. After the 
file is sorted, you have an ADDROUT file of records to be printed. The output 
of the sort becomes input to an RPG II program. Figure 30 shows the RPG II 
entries required to use the ADDROUT file as input to an RPG II program. 
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Figure 30, Processing by an ADDROUT File 
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FILES CONTAINING RECORD KEY LIMITS 


A record address file with record key limits contains the lowest and the highest 
key fields for a specified section of an indexed file. Record address files contain- 
ing record key limits can be entered from disk, card, or a printer-keyboard. They 
are used to process only indexed files. When a section of an indexed file is pro- 
cessed using record key limits, the processing method is known as sequential 
within limits. 


Creating a File with Record Key Limits 


The following rules must be observed when you create a record address file with 
record key limits: 


@ Only one record address file can be used for each RPG II program, but the 
record address file can contain several sets of limits. 


@ Only one set of limits is allowed on each record in a record address file. 
Since a set of limits is comprised of two keys, the length of each record ina 
record address file is twice as long as the length of the record key. 


@ The low record key must begin in position 1 of the record. 


® The high record key must immediately follow the low record key. No spaces 
are allowed between the two keys. If the key field were four bytes long and 
the low record key were 2000 and the high record key 3000, the record would 


look like this: 
| 20003000 


@ Each record key can be from 1 through 29 characters long. 


@ An alphameric record key can contain blanks. 


@ The length of the keys must equal the length of the key field in the indexed 
file. To make the length of the keys equal, leading zeros may have to be 
placed in a numeric record key or blanks in an alphameric record key. For 
example, if the low record key were three positions (200), the high record 
key four positions (2999), and the length of the key field in the indexed file 
four positions, a zero must be placed before the 200 to make it a 4-position 
number. The record would look like this: 


| 02002999 


Each key length must also equal the key field length you specify in columns 
29 and 30 of the File Description sheet. 


@ The same set of limits can appear on more than one record in a record address 
file. Therefore, records within a set of limits can be processed as many times 
as needed. 


@ The two record keys in a set of limits can be identical. For example, both the 
low and high record keys can be 2999. In this case, only one record (2999) 
will be processed. 
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Processing Sequentially within Limits 


Processing a section of an indexed file sequentially by record keys is known as 
sequential within limits processing. The RPG I! program uses one set of limits 
(one record in a record address file) ata time. Records are read from the section 
of the indexed file specified by the limits. When the records specified by one set 
of limits have been read, the program reads another set of limits from the record 
address file. The program continues reading records in this manner until the end 
of the record address file is reached. 


To process a file by a record address file using RPG II, entries must be made on 
the File Description and Extension sheets. Input specifications are not required. 


File Description Specifications 


The File Description sheet must describe both the indexed file to be processed 
and the record address file. The description of the indexed file to be processed 
must contain the following entries in addition to the other entries necessary to 
describe the file: 


File Description Specifications 


Mode of Processing 





Column 28 must contain an L to indicate that the records are to be read from 
this file sequentially within limits. Enter an A in column 31 to indicate that 
record keys are used in Processing the file. Enter an | in column 32 to indicate 
an indexed file. 


The record address file must be described with the following entries: 


File Description Specifications 





File Type 
Length of Key Field or 
Phe Desianstion of Record Address Field 


Filename Device 


File Format 


Block Record 
Length Length 


SB]? # 9 10:41 12:13:14 24 22.23 5 2 40 41 42 43 44 45 46)) 











The name of the record address file must be entered in columns 7 through 14. 
Column 15 must contain an | to indicate that the file is an input file. Enter an R 
in column 16 to indicate that the file is a record address file. 
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All records in a file must be the same length. Thus, column 19 contains an F to 

indicate that the record length is fixed. 


A number equal to or a multiple of the disk record length must be entered in 
columns 20 through 23. This entry determines the size of the input/output area 
allocated by RPG II. For an explanation on block length calculation, see the /BM 
System/3 Disk Concepts and Planning Guide, GC21-7571. \f you want block 
length calculated for you by RPG II, assign a block Jength equal to the record 
length. By blocking disk records you can increase the input/output efficiency of 
your program by reducing the number of accesses. You must be sure, however, 
that enough main storage is available for your input/output area. 


Columns 24 through 27 must contain the length of the disk record. Key length, 
entered in columns 29 and 30, is the same length for all records in a file. The max- 
imum record key length is 29 characters. 


Whenever a disk file is described, DISK (Models 6, 10, and 15), DISK40 (Model 12 or 15), 
or DISK45 (Model 10, 12, or 15) is required in the Device columns. Since additional 
information is given on the Extension sheet, column 39 must contain an E. 


Extension Specifications 


To process a file using a record address file, two entries must be made on the Exten- 
sion sheet: 
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To Filename 
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Columns 11 through 18 must contain the name of the record address file. The name 
must be the same as the record address file described on the File Description sheet. 


Columns 19 through 26 must contain the name of the file to be processed. This 
name must be the same filename defined on the File Description sheet. This entry 
indicates that the file is to be processed by the record address file coded in columns 
11 through 18. 


Example of Processing Sequentially within Limits 
You have a master customer file on disk consisting of 128-character records. The 
file is organized by customer number within customer class. Customers are sepa- 


rated into such classes as wholesalers or retailers. Together the customer number 
and class form a composite customer account number (key) in the form: ccnnonn. 


Record Address Files 85 


86 


The customer class is cc and the customer number is nnnnn. Customer classes 
begin at 01 and are in ascending order. Within each customer class, customer 
numbers range from 00000-99999. 


You must prepare separate reports for each customer class for sales analysis pur- 
poses. A record address file can be used to supply the particular class categories 
and customer number ranges as shown in Figure 31. The key in each disk record 
begins in position 2, and the record address file is loaded in MFCU1. Figure 32 
shows the necessary File Description and Extension entries for this job. 


Record address file 







03000000399999 





01000000199999 


0100000 


0199999 


0299999 


0300000 


0399999 


0499999 





Symbolic representation 
of customer ranges on 
the disk file, 


Figure 31. Files for Processing Sequentially within Limits 
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